home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audio / alIntro.z / alIntro
Encoding:
Text File  |  1998-10-20  |  11.8 KB  |  397 lines
  1.  
  2.  
  3.  
  4. aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alIntro, audio - Introduction to the Silicon Graphics Audio Library (AL)
  10.  
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  14.  
  15.      ----llllaaaauuuuddddiiiioooo
  16.  
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      The Silicon Graphics Audio Library (AL) provides a uniform, device-
  20.      independent programming interface to real-time audio I/O on Silicon
  21.      Graphics workstations.
  22.  
  23.      The AL was designed to enable multiple programs to share the audio
  24.      resources of the workstation. Multiple programs may have input and output
  25.      streams open concurrently, either sharing audio devices or using
  26.      independent audio devices.
  27.  
  28.      The Audio Library provides four major capabilities:
  29.  
  30.           1. input and output of digital audio data
  31.  
  32.           2. control of the attributes of the digital audio data
  33.  
  34.           3. control of physical parameters of the audio subsystem
  35.  
  36.           4. Audio subsystem event notification
  37.  
  38.      The first two of these capabilities are briefly described in the section
  39.      "Basic I/O." The device control capabilities are described in the section
  40.      "Resources and Control." The audio event notification model is described
  41.      in the "Audio Events" section.
  42.  
  43. BBBBAAAASSSSIIIICCCC IIII////OOOO
  44.      The basic data types for the Audio Library are AAAALLLLccccoooonnnnffffiiiigggg and AAAALLLLppppoooorrrrtttt.  An
  45.      application uses an AAAALLLLccccoooonnnnffffiiiigggg to define the attributes of the digital
  46.      audio data it wishes to send or receive. It then opens an AAAALLLLppppoooorrrrtttt, which
  47.      actually writes or reads the audio data to or from the hardware.
  48.  
  49.      The Audio Library includes the following functions:
  50.  
  51.      alNewConfig(3dm)         - create a new ALconfig
  52.  
  53.      alFreeConfig(3dm)        - free ALconfig
  54.  
  55.      alSetConfig(3dm)         - set an ALconfig on an existing ALport
  56.  
  57.      alGetConfig(3dm)         - get the ALconfig from an ALport
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      alSetQueueSize(3dm)      - set the sample queue size for an audio port
  75.  
  76.      alGetQueueSize(3dm)      - get the sample queue size for an audio port
  77.  
  78.      alSetWidth(3dm)          - set the sample wordsize for an audio port
  79.  
  80.      alGetWidth(3dm)          - get the sample wordsize for an audio port
  81.  
  82.      alSetSampFmt(3dm)        - set the sample data type and format for an
  83.                               audio port
  84.  
  85.      alGetSampFmt(3dm)        - get the sample data type and format for an
  86.                               audio port
  87.  
  88.      alSetChannels(3dm)       - set the number of channels for an audio port
  89.  
  90.      alGetChannels(3dm)       - get the number of channels for an audio port
  91.  
  92.      alSetFloatMax(3dm)       - set the max. amplitude of floating point data
  93.                               for an AL port
  94.  
  95.      alGetFloatMax(3dm)       - get the max. amplitude of floating point data
  96.                               for an AL port
  97.  
  98.      alSetLimiting(3dm)       - specify if limiting is required for floating-
  99.                               point data
  100.  
  101.      alGetLimiting(3dm)       - determine whether or not limiting is specified
  102.                               for an ALconfig
  103.  
  104.      alOpenPort(3dm)          - open an audio port and begin I/O
  105.  
  106.      alClosePort(3dm)         - close an audio port and stop I/O
  107.  
  108.      alGetFilled(3dm)         - get number of filled spots in an audio port
  109.  
  110.      alGetFillable(3dm)       - get number of fillable spots in an audio port
  111.  
  112.      alReadFrames(3dm)        - read interleaved sample frames from an audio
  113.                               port
  114.  
  115.      alWriteFrames(3dm)       - write interleaved sample frames to an audio
  116.                               port
  117.  
  118.      alZeroFrames(3dm)        - write zero-valued sample-frames to an output
  119.                               audio port
  120.  
  121.      alDiscardFrames(3dm)     - discard data from an input or output audio
  122.                               port
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      alReadBuffers(3dm)       - read flexibly interleaved or non-interleaved
  141.                               sample frames from an audio port
  142.  
  143.      alWriteBuffers(3dm)      - write flexibly interleaved or non-interleaved
  144.                               sample frames to an audio port
  145.  
  146.      alGetFD(3dm)             - get a file descriptor for an audio port, so
  147.                               that one can use _s_e_l_e_c_t(_2) or _p_o_l_l(_2) to block
  148.                               waiting for a fillpoint
  149.  
  150.      alSetFillPoint(3dm)      - define audio port high-/low-water mark
  151.                               (fillpoint) to unblock application
  152.  
  153.      alGetFillPoint(3dm)      - get the current fillpoint from an audio port.
  154.  
  155.      alGetFrameNumber(3dm)    - get the absolute sample frame number
  156.                               associated with a port
  157.  
  158.      alGetFrameTime(3dm)      - get the time at which a sample frame came in
  159.                               or will go out
  160.  
  161. RRRREEEESSSSOOOOUUUURRRRCCCCEEEESSSS AAAANNNNDDDD CCCCOOOONNNNTTTTRRRROOOOLLLL
  162.      The AL manages a number of hardware and software entities called
  163.      rrrreeeessssoooouuuurrrrcccceeeessss (see aaaallllRRRReeeessssoooouuuurrrrcccceeeessss((((3333ddddmmmm)))) for a more detailed description).
  164.      Resources include devices, ports, clock generators, master clocks,
  165.      connections, interfaces, subsystems, and the system resource.
  166.      Applications can acquire or change the state of the audio resources
  167.      through the following functions:
  168.  
  169.      alParams(3dm)
  170.           - general information about AL parameters
  171.  
  172.      alGetParams(3dm)
  173.           - get parameter values from an audio resource
  174.  
  175.      alSetParams(3dm)
  176.           - set parameter values on an audio resource
  177.  
  178.      alGetParamInfo(3dm)
  179.           - find out what kinds of values a parameter can have on a specific
  180.           resource
  181.  
  182.      alQueryValues(3dm)
  183.           - find the set of possible values for a discrete-valued parameter
  184.  
  185.      alIsSubtype(3dm)
  186.           - determine if one resource type is a subtype of another
  187.  
  188.      alGetResourceByName(3dm)
  189.           - find a resource with a given name
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206.      alConnect(3dm)
  207.           - connect the output of one audio I/O resource to the input of
  208.           another
  209.  
  210.      alDisconnect(3dm)
  211.           - disconnect one audio I/O resource from another
  212.  
  213. AAAAUUUUDDDDIIIIOOOO EEEEVVVVEEEENNNNTTTTSSSS
  214.      The AL provides event notification for applications interested in
  215.      monitoring audio system changes.  An audio event is represented by an
  216.      AAAALLLLeeeevvvveeeennnntttt structure.  This structure includes the parameter which changed
  217.      of event, the new parameter value in many cases, the time at which the
  218.      event was posted, and the sources of the event. Events are delivered to
  219.      each application via an _A_L_e_v_e_n_t_Q_u_e_u_e. Following is the list of event-
  220.      related functions:
  221.  
  222.      alOpenEventQueue(3dm)
  223.           - Allocate and initialize an event queue
  224.  
  225.      alCloseEventQueue(3dm)
  226.           - Deallocate a previously initialized event queue
  227.  
  228.      alNewEvent(3dm)
  229.           - Allocate and initialize an event
  230.  
  231.      alFreeEvent(3dm)
  232.           - Deallocate a previously initialized event
  233.  
  234.      alSelectEvents(3dm)
  235.           - Select events to be received into event queue
  236.  
  237.      alDeselectEvents(3dm)
  238.           - Deselect events from event queue
  239.  
  240.      alGetEventQueueFD(3dm)
  241.           - Get file descriptor of event queue
  242.  
  243.      alNextEvent(3dm)
  244.           - Retrieves the next event from an event queue
  245.  
  246.      alCheckEvent(3dm)
  247.           - Check for a particular event in an event queue
  248.  
  249.      alPendingEvents(3dm)
  250.           - Get the number of pending events in an event queue
  251.  
  252.      alFlushEvents(3dm)
  253.           - Flush all events from event queue
  254.  
  255.      alGetEventParam(3dm)
  256.           - Returns the event parameter
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  269.  
  270.  
  271.  
  272.      alGetEventResource(3dm)
  273.           - Returns the id of the resource that posted the event
  274.  
  275.      alGetEventSrcResource(3dm)
  276.           - Returns the id of the resource that generated the event
  277.  
  278.      alGetEventUST(3dm)
  279.           - Returns the Unadjusted System Time of an event
  280.  
  281.      alGetEventValue(3dm)
  282.           - Return the new value of the event parameter
  283.  
  284.      alGetEventData(3dm)
  285.           - Returns a pointer to an event info struct
  286.  
  287. MMMMIIIISSSSCCCCEEEELLLLLLLLAAAANNNNEEEEOOOOUUUUSSSS
  288.      alGetErrorString(3dm)
  289.           - get a text message associated with an AL error return code
  290.  
  291.      alDoubleToFixed(3dm)
  292.           - convert from double-precision to AL-format fixed-point
  293.  
  294.      alFixedToDouble(3dm)
  295.           - convert from AL-format fixed-point to double-precision
  296.  
  297.      alSetErrorHandler(3dm)
  298.           - specify a user-defined error handler, if desired
  299.  
  300.      /usr/include/dmedia/audio.h        - Audio Library header file
  301.  
  302.      /usr/share/src/dmedia/audio/*      - code examples
  303.  
  304.      /usr/share/src/dmedia/soundcommands/*   - code examples
  305.  
  306.      /usr/share/src/dmedia/soundplayer/*     - code examples
  307.  
  308.  
  309. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  310.      DOCUMENTATION:
  311.  
  312.           Digital Media Programming Guide: Audio, MIDI, Video, and Compression
  313.  
  314.      RELATED LIBRARIES:
  315.  
  316.           AFintro(3dm) - Introduction to the Audio File Library
  317.  
  318.           CDaudio(3) - Introduction to the audio Compact Disc library
  319.  
  320.           DATaudio(3) - Introduction to the Digital Audio Tape Library
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))                                                      aaaallllIIIInnnnttttrrrroooo((((3333ddddmmmm))))
  335.  
  336.  
  337.  
  338.           mdIntro(3dm) - Introduction to the Silicon Graphics MIDI Library
  339.           (libmd)
  340.  
  341.      IRIX Real-time Support:
  342.  
  343.           select(2), sproc(2), setitimer(2), schedctl(2), prctl(2), poll(2),
  344.           mpin(2)
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.